package org.apache.mina.protocol.dns;

import java.net.InetAddress;
import java.util.List;

import org.apache.mina.common.IoFuture;
import org.apache.mina.common.IoFutureListener;

/**
 * An {@link IoFuture} for asynchronous DNS lookups.
 *
 * <h3>Example</h3>
 * <pre>
 * DnsResolver resolver = ...;
 * DnsFuture future = resolver.resolve("www.google.com");
 * future.join(); // Wait until the DNS lookup attempt is finished.
 * if ( ! future.isNameError() )
 *    InetAddress address = future.get();
 * </pre>
 *
 * @author The Apache MINA Project (dev@mina.apache.org)
 * @version $Rev: 84 $, $Date: 2008-02-22 16:33:48 +0000 (Fri, 22 Feb 2008) $
 */
public interface DnsFuture extends IoFuture {

    /**
     * @return true if a name lookup error occurred
     */
    boolean isNameError();

    /**
     * @return the host name is beeing looking up
     */
    String getHostname();

    /**
     * Get the first {@link InetAddress} of all the addresses
     * resolved for the given domain
     * 
     * @return a resolved address for the domain
     */
    InetAddress get();

    /**
     * Get a list of all addresses resolved for the domain.
     * 
     * @return a list of addresses
     */
    List<InetAddress> getAll();

    /* (non-Javadoc)
     * @see org.apache.mina.common.IoFuture#await()
     */
    DnsFuture await() throws InterruptedException;

    /* (non-Javadoc)
     * @see org.apache.mina.common.IoFuture#awaitUninterruptibly()
     */
    DnsFuture awaitUninterruptibly();

    /* (non-Javadoc)
     * @see org.apache.mina.common.IoFuture#addListener(org.apache.mina.common.IoFutureListener)
     */
    DnsFuture addListener(IoFutureListener<?> listener);

    /* (non-Javadoc)
     * @see org.apache.mina.common.IoFuture#removeListener(org.apache.mina.common.IoFutureListener)
     */
    DnsFuture removeListener(IoFutureListener<?> listener);
}
